# First startup ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- # Safety information (read carefully) > 💡 **Hardware usage requirements** - Please use the USB-A power cable (5 A) provided in the kit. **Do not use a power supply rated for an output current below 3 A**(such as a mobile phone charger); otherwise, the Quectel Pi H1 smart single-board computer may be underpowered or repeatedly shut down abnormally. If you need to connect a high-power module (such as a motor), power the module separately. Do not draw power through the Quectel Pi H1's USB or GPIO port, to avoid overload and damage to the Quectel Pi H1. - When connecting or disconnecting accessories (such as a camera cable or network cable), **you must disconnect the power to the Quectel Pi H1 first**, because hot-plugging may damage the interface chips. The USB & DP interface supports only DP display and power output; it cannot be used to power the smart single-board computer. - Operating temperature: -20 to +70 °C. Do not use the computer in high-temperature environments (e.g., direct sunlight), humid (humidity >80%), or dusty environments. Before operation, please touch a metal object to discharge static electricity, and avoid touching the chip pins on the single-board computer directly with your hands. **System and software precautions** - Only system images officially provided for this product are supported. Do not flash an image for another smart single-board computer (such as a Raspberry Pi); otherwise, driver incompatibility, failure to boot or other problems may occur. - If you need to customize the system, use [Yocto Linux SDK]() for development, and ensure that the kernel version and driver modules are compatible with Quectel Pi H1. - Do not modify the core configuration files (such as ***config.txt***) under the ***/boot*** partition; otherwise, the system may fail to boot. If modification is necessary, back up the corresponding files first. - When installing software, preferably use the ***apt*** command to download packages from official repositories. Avoid installing DEB packages from unknown sources to reduce the risk of malware infection or system faults. # Preparation Depending on the use case, choose one of two configuration options: an external display or an ADB connection. √ indicates required, and ○ indicates optional. | **Accessory** | **Requirements** | **External display** | **ADB connection** | | --- | --- | --- | --- | | Quectel Pi H1 smart single-board computer | — | √ | √ | | Power adapter | 5 V / 5 A or 9 V / 3 A PD | √ | √ | | Network cable | Connect to a router or use Wi-Fi | ○ | ○ | | Display | Desktop / laptop / MIPI display | √ | ○ | | USB-C DP / HDMI cable | Connect to the display | ○ | ○ | | Keyboard / mouse | USB wired/wireless | √ | √ | | Desktop / laptop | For running terminal software | ○ | √ | | USB Type-C to USB Type-A data cable | Connect the Quectel Pi H1 to the desktop | ○ | √ | # Preparation before powering on The header pins marked **AUTO_POWER_ON** at the upper-left corner of the Quectel Pi H1 must be shorted with a jumper cap to enable automatic startup when power is applied. **Jumper cap status description:** | **Status** | **Appearance** | **Behavior** | | --- | --- | --- | | Shorted (recommended) | The jumper cap is placed over both header pins, electrically connecting them. | The system starts automatically when power is connected; no additional operation is required. | | Not shorted | The jumper cap is not installed or is placed on only one pin (left floating). | After power is connected, the system does not start automatically; press and hold the PWRKEY button to power it on manually. | ```{image} images/image_VvJPbMXptoIKk5xwoGPcZmZqndg.webp :width: 600px :height: 373px ``` ```{image} images/image_SR2zb37IZosNdAx0QSmcuVREnGS.webp :width: 948px :height: 761px :align: center ``` ```{note} If AUTO_POWER_ON is not shorted, press and hold the PWRKEY button after powering on to start the system. ``` # Select a use case Quectel Pi H1 smart single-board computer is shipped with the Debian 13 system image by default, so reflashing is normally unnecessary. Select the appropriate startup method according to your equipment: | **Scenario** | **Applicable conditions** | **Go to** | | --- | --- | --- | | **With an external display** | HDMI / USB-C DP / MIPI display, keyboard, and mouse available | [Start the Quectel Pi H1 with an external display](#start-the-quectel-pi-h1-with-an-external-display) | | **Without an external display** | No display, but a USB-C data cable and a computer are available | [Start the Quectel Pi H1 without a display](#start-the-quectel-pi-h1-without-a-display) | ## Start the Quectel Pi H1 with an external display ### Hardware connections ```{image} images/image_FKTVbW82gohghjxf4vecPAwUnzc.webp :width: 925px :height: 617px :align: center ``` 1. **Display connection:** Select one of the following connection methods according to the display interface. The figure above uses method 2 (HDMI connection) as an example; **Method 1 (USB-C DP connection):** Connect one end of the USB-C DP display cable to Quectel Pi H1's USB & DP interface and the other end to the display's USB-C interface. **Method 2 (HDMI connection):** Connect one end of the HDMI cable to Quectel Pi H1's HDMI and the other end to the display's HDMI, as shown above. **Method 3 (MIPI display):** Make sure that the gold fingers of the flex cable and the contacts of the connector are on the same side. Insert the cable fully, then press down the latch to secure it, so as to avoid no display due to incorrect orientation. For details, see the [MIPI](<../../Usage guide/Display/MIPI/MIPI.md>). 2. **Network connection:** Connect one end of the Gigabit network cable to the Quectel Pi H1's Gigabit network port and the other end to the router's network port (alternative: connect through Wi-Fi; see [Wi-Fi configuration](<../../Operating system/Debian/qpi-config/qpi-config.md#>)); 3. **Input-device connection:** Connect a USB keyboard and mouse to the Quectel Pi H1's USB-A ports. For wireless input devices, insert the receiver into the USB ports. 4. **Power connection:** Connect the USB-A end of the power cable to the power adapter and the USB-C end to the power port on the Quectel Pi H1 marked **POWER IN**. ### System startup - Turn on the display and make sure its input source is switched to the corresponding interface (such as USB-C or HDMI). - Connect power to the Quectel Pi H1. When the power LED (red) remains on and the system LED (green) flashes, the system is starting. - Wait approximately 1–2 minutes for the system login screen to appear on the display. ```{note} If the header pins marked **AUTO_POWER_ON** are not shorted with a jumper cap during hardware connection, first press and hold **PWRKEY** on the right side of Quectel Pi H1, then connect power and hold it until the system starts.**If the system fails to start normally, reflash the system image:** 1. [Download the Debian 13 image](). 2. [Download and install the USB driver](). 3. Power the Quectel Pi H1 with a compliant power adapter. 4. Connect the Quectel Pi H1 USB & DP interface to the computer. 5. Follow the [System installation](<../../Operating system/Debian/System installation/System installation.md>). ``` ### System login For information about setting the username and password, see [System login](<../../Operating system/Debian/System login/System login.md>). ```{note} The ***root*** account has no password by default. Please set the password before use. If you open the **Enterprise Login** interface while creating a user and cannot exit, click **Enterprise Login** again to return to the user-creation screen. ``` ```{image} images/image_XFEubP2gIojrJcxXQHbc0KZEnbg.webp :width: 1280px :height: 960px ``` ### Network configuration Select the Wi-Fi network and enter its password to connect. ```{image} images/image_OqJjbsMs6oPteQxgyGQcdrPLnRd.webp :width: 961px :height: 608px :align: center ``` ### Open the terminal command line ```{image} images/image_Vc71bhDw6oQJfmxmBTqcekg4n0d.webp :width: 1675px :height: 954px ``` ## Start the Quectel Pi H1 without a display If the Quectel Pi H1 is not connected to a display, keyboard, or mouse, you can control it remotely from another computer. To control the Quectel Pi H1 remotely, first connect it to a network, then access it using a client on another device. SSH provides remote access to the command-line terminal, while VNC provides remote access to the graphical desktop. If the device is not yet connected to the network, first use **ADB** to complete the initial network configuration. For additional remote-access methods, see [Device connection](<../../Usage guide/Device connection/Device connection.md>). | **Method** | **Description** | **Prerequisites** | **Tutorial link** | | --- | --- | --- | --- | | VNC | Remote access to the graphical desktop | Device is connected to the network | [VNC remote desktop](<../../Usage guide/Device connection/VNC remote desktop/VNC remote desktop.md>) | | SSH | Remote access to the command-line terminal | Device is connected to the network | [SSH remote terminal](<../../Usage guide/Device connection/SSH remote terminal/SSH remote terminal.md>) | ```{note} During first startup, it is recommended to configure Wi-Fi through ADB first; you can then use VNC or SSH for daily operations. ``` ### Connect to the Quectel Pi H1 through ADB This method allows you to remotely log in to and control the Quectel Pi H1 without an external display. Download the ADB tools: [platform-tools](). ### Install ADB Extract the downloaded *platform-tools* to a specified folder on the computer. ### Confirm that the ADB device is recognized ```{image} images/image_PkuzbUXldoXvsZx6NvlcovRanIh.webp :width: 972px :height: 663px :align: center ``` Connect the Quectel Pi H1 to the computer with a USB type-C cable, open a terminal in the ADB tools directory, and run the following command: ```bash adb devices ``` Example output: ```plaintext List of devices attached 790c2fb9 device ``` ```{note} If the device status is *unauthorized*, or no device is displayed, make sure that the USB cable supports data transfer rather than charging only, or try another USB port. ``` ### **Connect to the device through ADB** ```bash adb shell ``` After the connection succeeds, operations are performed as the root user. ### Create a regular user The system provides only the root user by default. Creating a regular user for daily operations is recommended. **Create a user** The following example creates a user named *pi*; you can specify another username. ```bash adduser pi #pi is the name of the user being created ``` The system prompts you to set a password. Enter the password twice as instructed. ```{image} images/image_Nk9ubk6k1oTztRxWUKWcBzTQnTf.webp :width: 437px :height: 208px ``` After the user is created, the system automatically creates */home/username* as the user's home directory. You can store personal files, project code, and other information in this directory. **Grant*sudo*****privileges** ```bash usermod -aG sudo pi ``` **Switch users** ```bash #verify the user id pi #switch user su - pi #test permissions whoami sudo whoami #should output root; verify sudo privileges ``` ### Connect to Wi-Fi The Quectel Pi H1 includes the qpi-config tool for managing Wi-Fi connections. **Scan nearby Wi-Fi networks** ```bash qpi-config wifi scan ``` ```{image} images/image_EVFGbGXzFoekdTxjbo0cGG2Tn2c.webp :width: 785px :height: 202px ``` **Connect to Wi-Fi** ```bash #connect to Wi-Fi qpi-config wifi connect "your_Wi-Fi_name" "your_Wi-Fi_password" #view saved Wi-Fi connections qpi-config wifi show #delete saved Wi-Fi connections qpi-config wifi remove ``` ```{image} images/image_PuCsbdhjPoc5ghxnW4wcPylFnge.webp :width: 650px :height: 105px ``` **Verify network connectivity** ```bash ping www.google.com ``` ### Connect to the smart single-board computer through SSH **View the device IP address** Run *ifconfig* in the smart single-board computer's terminal to obtain its IP address. The device IP address in this example is *10.55.62.206*. ```{image} images/image_NXUCbP3yJoiwnOxSxJOcQjzcnvb.webp :width: 651px :height: 456px :align: center ``` **Connect to the smart single-board computer through SSH using QPiTerminal** Open **QPiTerminal** and create a **SSH** session. Enter the smart single-board computer's **IP** address, username, and password, then click **Connect**. ```{image} images/image_SnQEbYVejo5rvXxuvTGcGS1Ln0d.webp :width: 1501px :height: 806px :align: center ``` ```{image} images/image_FppAb1jj0on61ixqw8Dc3LfKnrg.webp :width: 1506px :height: 813px :align: center ``` # System health check After the system starts, use ***qpi-config*** in the terminal to quickly check the system status. ## Check the temperature of each system module ```bash sudo qpi-config dump temperature ``` ```{image} images/image_SKyXbT4zmoZXlvxkwBucGRkFnlb.webp :width: 1012px :height: 567px :align: center ``` ## Check system CPU, memory, and storage status ```bash sudo qpi-config dump systemusage ``` ```{image} images/image_Ul4SbMelfogtlrxV0T2c1fBDnqh.webp :width: 917px :height: 378px :align: center ``` ## Network status check After connecting the device to the network through a network cable or Wi-Fi, use **ping** to verify that it can access the external network. ```bash ping www.google.com ``` **Example output for a successful connection:** ```plaintext PING www.google.com (142.251.150.119) 56(84) bytes of data. 64 bytes from 142.251.150.119: icmp_seq=1 ttl=106 time=66.6 ms 64 bytes from 142.251.150.119: icmp_seq=2 ttl=106 time=66.8 ms 64 bytes from 142.251.150.119: icmp_seq=3 ttl=106 time=67.0 ms 64 bytes from 142.251.150.119: icmp_seq=4 ttl=106 time=67.1 ms 64 bytes from 142.251.150.119: icmp_seq=5 ttl=106 time=65.9 ms 64 bytes from 142.251.150.119: icmp_seq=6 ttl=106 time=66.7 ms 64 bytes from 142.251.150.119: icmp_seq=7 ttl=106 time=68.2 ms ^C --- www.google.com ping statistics --- 7 packets transmitted, 7 received, 0% packet loss, time 6010ms rtt min/avg/max/mdev = 65.918/66.899/68.156/0.624 ms ``` ```{note} **Identifier descriptions:** *64 bytes from ...*: An ICMP response (reply) was received, indicating normal network connectivity *icmp_seq*: Sequence number; increasing values indicate that responses continue to be received *ttl*: Time to live; the normal range is generally 30–128 *time*: Round-trip latency; a smaller value indicates better network quality *0% packet loss*: A 0% packet-loss rate, indicating that no packets were lost in this test ``` ```{image} images/image_EYv6bQRNDo3DFXxNSiOce4Lmn1e.webp :width: 502px :height: 224px :align: center ``` # First Hello World program ## Set up the development environment After logging in to the Quectel Pi H1 Debian system, open a terminal window, enter the following command, and press **Enter** to install the required development environment. ```bash sudo apt update && sudo apt install gcc make ``` ## Compile and run helloworld (C version) 1. Open the system terminal and run the following command to create *hello.c*. ```bash touch hello.c ``` 2. Run the following command to open ***nano*** in the *hello.c* editor. ```bash sudo nano hello.c ``` 3. Copy the following code to *hello.c*. Press **Ctrl+O** and **Enter** to save, then press **Ctrl+X** to exit the ***nano*** editor. ```c #include int main(void) { printf("hello world\r\n"); return 0; } ``` 4. Run the following command to compile the code: ```bash gcc hello.c -o hello ``` 5. Run the following command to execute the hello program: ```bash ./hello ``` 6. The program output is as follows: ```plaintext ./hello hello world ``` ## Compile and run helloworld (Python version) In addition to C, you can quickly implement a Hello World program in Python. The Python environment is preinstalled, so no additional interpreter is required. 1. Open the system terminal and enter the following command to create *hello.py*. ```bash touch hello.py ``` 1. Open **Files** in the system, then in the *Home* directory, double-click *hello.py*. 2. Copy the following code and paste it into *hello.py*: ```python def main(): print("Hello, World!") if __name__ == "__main__": main() ``` 4. Python is an interpreted language, so no compilation is required; execute it directly: ```bash python3 hello.py ``` 5. The program output is as follows: ```plaintext python3 hello.py Hello, World! ``` ## Purpose A Hello World program can verify that the development environment has been set up successfully. Writing and running a simple C or Python program checks whether the compiler and runtime environment work correctly and also provides an introductory exercise in embedded development. # Safe power-off and restart Quectel Pi H1 supports safe power-off or restart in three ways: through the graphical desktop interface, the command line, or a physical button. ## Power off through the graphical desktop interface If you are using an external display in the desktop environment: 1. Click the system menu in the upper-right corner of the desktop. 2. Select **Power Off** or **Restart**. ```{image} images/image_OcJhbEM1Yoaz5Ixcbp6cEbFqnyf.webp :width: 1920px :height: 1080px ``` ## Power off through the command line Run the following commands in a terminal (local terminal, SSH, or ADB shell): **Power off** ```bash sudo poweroff ``` **Restart** ```bash sudo reboot ``` ## Power off with the physical button Press and hold the **PWRKEY** button on the right side of the Quectel Pi H1 for approximately 3–5 seconds; the system performs a safe power-off. ```{note} Wait for the system indicator LED1 (green) to turn off before disconnecting the power cable. When this LED turns off, the system has stopped running and it is safe to disconnect power. ``` # Suggestions for further study After completing the introductory operations, you can learn more about the following: - [Supported accessories](<../../Supported accessories/Supported accessories.md>) - [Usage guide](<../../Usage guide/Usage guide.md>) - [Operating system](<../../Operating system/Operating system.md>) - [Application development](<../../Application development/Application development.md>) - [Edge Computing](<../../Edge Computing/Edge Computing.md>) - [Development tool](<../../Development tool/Development tool.md>) - [Components and drivers support list](<../../Components and drivers support list/Components and drivers support list.md>) - [FAQ](<../../FAQ/FAQ.md>)